ajSendEmails function

Available since AlchemyJ v5.0

Description

The ajSendEmails function sends emails to the recipients with given subjects, messages, and attachments.

Syntax

ajSendEmails(subject,message,to_address,[cc_address],[bcc_address],[attachment_path],[html_mail],[smtp_id],[host],[port],[username],[password],[sender_address],[run_condition],[run_by_function_point_only])

Argument Name	Argument Type	Description
subject (required)	Range	The subject for the email.
message (required)	Range	The content of the email message from a range of cells. The range of cells can span across multiple rows and columns. Each row represents an email's message, the values of all columns in same row will be concatenated.
to_address (required)	Range	To email address from a range of cells. The range of cells can span across multiple rows and columns. Each cell should be contain one email address.
cc_address (optional)	Range	CC email address from a range of cells. The range of cells can span across multiple rows and columns. Each cell should be contain one email address.
bcc_address (optional)	Range	BCC email address from a range of cells. The range of cells can span across multiple rows and columns. Each cell should be contain one email address.
attachment_path (optional)	Range	The attachment file paths of the email from a range of cells. The range of cells can span across multiple rows and columns. Each cell contains on file path.
html_mail (optional)	Boolean	If it equals FALSE, the function will process the Body as plain text. If it equals TRUE, the function will process the Body as HTML formatted. The default value is FALSE.
smtp_id (optional)	String	The SMTP Connection ID defined in worksheet ##ExternalResources. If it is omitted, parameter 'host','port', 'sender_address' become mandatory. If a 'smtp_id' is provided and 'host', 'port', 'username', 'password' or 'sender_address' are not empty, they will overwrite the configuration defined in smtp_id in ##ExternalResources.
host (optional)	String	The IP address or FQDN of the SMTP server.
port (optional)	Number	The listening port of the email service of the SMTP server. It should be a positive integer.
username (optional)	String	The email account login user name.
password (optional)	String	The password for the username.
sender_address (optional)	String	FROM email address.
run_condition (optional)	Boolean	The function will run when the value is TRUE. Otherwise will not run. The default value is TRUE.
run_by_function_point_only (optional)	Boolean	If it equals FALSE, the function can be executed through ‘Excel Calculation’ (can be either Automatic or Manual, Calculate Now or Calculate Sheet) or Preview Function Point. If it equals TRUE, the function can be executed with Preview Function Point (AlchemyJ ribbon \ Preview Function Point) only. The default value is TRUE.

The function will return:

1) Return Value: TRUE / FALSE + Error Message / #VALUE

2) Return Type: Single Value / Multiple values (array formula)

Prerequisite

1. Setup the STMP Connection and use the STMP Connection ID as "primary". The mail server information could be setup in ##ExternalResources .

Example

1. Make sure the AlchemyJ Function Proxy was started up when executing ajSendEmails in the AlchemyJ workbook. You can start the proxy from More Tools - Run AlchemyJ Function Proxy.

2. Below example sends multiple emails to different email addresses.

{=ajSendEmails(B1:B2,B3:B4,B5:B6,B7:B8,B9:B10,B11:B12,B13,B14,,,,,B19,B20,B21)}

The result is TRUE that indicates the email has been sent out successfully. However, it does not necessarily mean the recipient can receive or has received the email. Whether a recipient receives the email depends on how the mail server handles the email. That is beyond the reach of this function.

It will return FALSE with error message when any of the email has error.

As Html_mail is TRUE and an email body is in HTML format, the mail client displays the content with HTML formatting.

Error Scenarios

It will return #VALUE! when missing any required parameter or mismatch parameter type in all records. Besides, system will raise error for below scenario(s).

Error Scenario
SMTP connection does not exist.
Failed to send email.
Host or port has not been provided while not using the smtp_id to send email.
Invalid SMTP connection id.
Both of records messages are empty.
Both of records sender addresses are empty.
Both of records to address is empty.
Username is empty while the password is provided.
The sizes of Subject, To address and Message are different.